home *** CD-ROM | disk | FTP | other *** search
/ Game Programming in C++ - Start to Finish / GameProgrammingS.iso / developer_install / CEGUISDK-0.4.1-VC6-STLport.exe / {app} / include / CEGUIImage.h < prev    next >
C/C++ Source or Header  |  2005-07-21  |  17KB  |  496 lines
  1. /************************************************************************
  2.     filename:     CEGUIImage.h
  3.     created:    13/3/2004
  4.     author:        Paul D Turner
  5.     
  6.     purpose:    Defines interface for Image class
  7. *************************************************************************/
  8. /*************************************************************************
  9.     Crazy Eddie's GUI System (http://www.cegui.org.uk)
  10.     Copyright (C)2004 - 2005 Paul D Turner (paul@cegui.org.uk)
  11.  
  12.     This library is free software; you can redistribute it and/or
  13.     modify it under the terms of the GNU Lesser General Public
  14.     License as published by the Free Software Foundation; either
  15.     version 2.1 of the License, or (at your option) any later version.
  16.  
  17.     This library is distributed in the hope that it will be useful,
  18.     but WITHOUT ANY WARRANTY; without even the implied warranty of
  19.     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  20.     Lesser General Public License for more details.
  21.  
  22.     You should have received a copy of the GNU Lesser General Public
  23.     License along with this library; if not, write to the Free Software
  24.     Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
  25. *************************************************************************/
  26. #ifndef _CEGUIImage_h_
  27. #define _CEGUIImage_h_
  28.  
  29. #include "CEGUIBase.h"
  30. #include "CEGUIString.h"
  31. #include "CEGUIRect.h"
  32. #include "CEGUIColourRect.h"
  33. #include "CEGUIVector.h"
  34. #include "CEGUISize.h"
  35. #include "CEGUIRenderer.h"
  36. #include <map>
  37.  
  38.  
  39. #if defined(_MSC_VER)
  40. #    pragma warning(push)
  41. #    pragma warning(disable : 4251)
  42. #endif
  43.  
  44.  
  45. // Start of CEGUI namespace section
  46. namespace CEGUI
  47. {
  48. /*!
  49. \brief
  50.     Class that represents a single Image of an Imageset.
  51. */
  52. class CEGUIEXPORT Image
  53. {
  54. public:
  55.     /*!
  56.     \brief
  57.         Return a Size object containing the dimensions of the Image.
  58.  
  59.     \return
  60.         Size object holding the width and height of the Image.
  61.     */
  62.     Size    getSize(void) const            {return Size(d_scaledWidth, d_scaledHeight);}
  63.     
  64.  
  65.     /*!
  66.     \brief
  67.         Return the pixel width of the image.
  68.  
  69.     \return
  70.         Width of this Image in pixels.
  71.     */
  72.     float    getWidth(void) const        {return d_scaledWidth;}
  73.  
  74.  
  75.     /*!
  76.     \brief
  77.         Return the pixel height of the image.
  78.  
  79.     \return
  80.         Height of this Image in pixels
  81.     */
  82.     float    getHeight(void) const        {return d_scaledHeight;}
  83.  
  84.  
  85.     /*!
  86.     \brief
  87.         Return a Point object that contains the offset applied when rendering this Image
  88.  
  89.     \return
  90.         Point object containing the offsets applied when rendering this Image
  91.     */
  92.     Point    getOffsets(void) const        {return d_scaledOffset;}
  93.  
  94.  
  95.     /*!
  96.     \brief
  97.         Return the X rendering offset
  98.  
  99.     \return
  100.         X rendering offset.  This is the number of pixels that the image is offset by when rendering at any given location.
  101.     */
  102.     float    getOffsetX(void) const        {return    d_scaledOffset.d_x;}
  103.  
  104.  
  105.     /*!
  106.     \brief
  107.         Return the Y rendering offset
  108.  
  109.     \return
  110.         Y rendering offset.  This is the number of pixels that the image is offset by when rendering at any given location.
  111.     */
  112.     float    getOffsetY(void) const        {return d_scaledOffset.d_y;}
  113.  
  114.  
  115.     /*!
  116.     \brief
  117.         Return the name of this Image object.
  118.  
  119.     \return
  120.         String object containing the name of this Image
  121.     */
  122.     const String&    getName(void) const;
  123.  
  124.  
  125.     /*!
  126.     \brief
  127.         Return the name of the Imageset that contains this Image
  128.  
  129.     \return
  130.         String object containing the name of the Imageset which this Image is a part of.
  131.     */
  132.     const String&    getImagesetName(void) const;
  133.  
  134.     /*!
  135.     \brief
  136.         Return Rect describing the source texture area used by this Image.
  137.  
  138.     \return
  139.         Rect object that describes, in pixels, the area upon the source texture
  140.         which is used when rendering this Image.
  141.     */
  142.     const Rect& getSourceTextureArea(void) const;
  143.  
  144.     /*!
  145.     \brief
  146.         Queue the image to be drawn. 
  147.         
  148.     \note
  149.         The final position of the Image will be adjusted by the offset values defined for this Image object.  If absolute positioning is
  150.         essential then these values should be taken into account prior to calling the draw() methods.  However, by doing this you take
  151.         away the ability of the Imageset designer to adjust the alignment and positioning of Images, therefore your component is far
  152.         less useful since it requires code changes to modify image positioning that could have been handled from a data file.
  153.  
  154.     \param position
  155.         Vector3 object containing the location where the Image is to be drawn
  156.  
  157.     \param size
  158.         Size object describing the size that the Image is to be drawn at.
  159.  
  160.     \param clip_rect
  161.         Rect object that defines an on-screen area that the Image will be clipped to when drawing.
  162.  
  163.     \param top_left_colour
  164.         Colour (as 0xAARRGGBB value) to be applied to the top-left corner of the Image.
  165.  
  166.     \param top_right_colour
  167.         Colour (as 0xAARRGGBB value) to be applied to the top-right corner of the Image.
  168.  
  169.     \param bottom_left_colour
  170.         Colour (as 0xAARRGGBB value) to be applied to the bottom-left corner of the Image.
  171.  
  172.     \param bottom_right_colour
  173.         Colour (as 0xAARRGGBB value) to be applied to the bottom-right corner of the Image.
  174.     
  175.     \param quad_split_mode
  176.         One of the QuadSplitMode values specifying the way quads are split into triangles
  177.  
  178.     \return
  179.         Nothing
  180.     */
  181.     void    draw(const Vector3& position, const Size& size, const Rect& clip_rect, const colour& top_left_colour = 0xFFFFFFFF, const colour& top_right_colour = 0xFFFFFFFF, const colour& bottom_left_colour = 0xFFFFFFFF, const colour& bottom_right_colour = 0xFFFFFFFF, QuadSplitMode quad_split_mode = TopLeftToBottomRight) const
  182.     {
  183.         draw(Rect(position.d_x, position.d_y, position.d_x + size.d_width, position.d_y + size.d_height), position.d_z, clip_rect, 
  184.             ColourRect(top_left_colour, top_right_colour, bottom_left_colour, bottom_right_colour), quad_split_mode);
  185.     }
  186.  
  187.  
  188.     /*!
  189.     \brief
  190.         Queue the image to be drawn.
  191.  
  192.     \note
  193.         The final position of the Image will be adjusted by the offset values defined for this Image object.  If absolute positioning is
  194.         essential then these values should be taken into account prior to calling the draw() methods.  However, by doing this you take
  195.         away the ability of the Imageset designer to adjust the alignment and positioning of Images, therefore your component is far
  196.         less useful since it requires code changes to modify image positioning that could have been handled from a data file.
  197.  
  198.     \param dest_rect
  199.         Rect object defining the area on-screen where the Image is to be drawn.  The Image will be scaled to fit the area as required.
  200.  
  201.     \param z
  202.         Z-order position for the image.  Positions increase "into the screen", so 0.0f is at the top of the z-order.
  203.  
  204.     \param clip_rect
  205.         Rect object that defines an on-screen area that the Image will be clipped to when drawing.
  206.  
  207.     \param top_left_colour
  208.         Colour (as 0xAARRGGBB value) to be applied to the top-left corner of the Image.
  209.  
  210.     \param top_right_colour
  211.         Colour (as 0xAARRGGBB value) to be applied to the top-right corner of the Image.
  212.  
  213.     \param bottom_left_colour
  214.         Colour (as 0xAARRGGBB value) to be applied to the bottom-left corner of the Image.
  215.  
  216.     \param bottom_right_colour
  217.         Colour (as 0xAARRGGBB value) to be applied to the bottom-right corner of the Image.
  218.     
  219.     \param quad_split_mode
  220.         One of the QuadSplitMode values specifying the way quads are split into triangles
  221.  
  222.     \return
  223.         Nothing
  224.     */
  225.     void    draw(const Rect& dest_rect, float z, const Rect& clip_rect, const colour& top_left_colour = 0xFFFFFFFF, const colour& top_right_colour = 0xFFFFFFFF, const colour& bottom_left_colour = 0xFFFFFFFF, const colour& bottom_right_colour = 0xFFFFFFFF, QuadSplitMode quad_split_mode = TopLeftToBottomRight) const
  226.     {
  227.         draw(dest_rect, z, clip_rect, ColourRect(top_left_colour, top_right_colour, bottom_left_colour, bottom_right_colour), quad_split_mode);
  228.     }
  229.  
  230.  
  231.     /*!
  232.     \brief
  233.         Queue the image to be drawn. 
  234.         
  235.     \note
  236.         The final position of the Image will be adjusted by the offset values defined for this Image object.  If absolute positioning is
  237.         essential then these values should be taken into account prior to calling the draw() methods.  However, by doing this you take
  238.         away the ability of the Imageset designer to adjust the alignment and positioning of Images, therefore your component is far
  239.         less useful since it requires code changes to modify image positioning that could have been handled from a data file.
  240.  
  241.     \param position
  242.         Vector3 object containing the location where the Image is to be drawn
  243.  
  244.     \param size
  245.         Size object describing the size that the Image is to be drawn at.
  246.  
  247.     \param clip_rect
  248.         Rect object that defines an on-screen area that the Image will be clipped to when drawing.
  249.  
  250.     \param colours
  251.         ColourRect object that describes the colour values to use for each corner of the Image.
  252.     
  253.     \param quad_split_mode
  254.         One of the QuadSplitMode values specifying the way quads are split into triangles
  255.  
  256.     \return
  257.         Nothing
  258.     */
  259.     void    draw(const Vector3& position, const Size& size, const Rect& clip_rect, const ColourRect& colours, QuadSplitMode quad_split_mode = TopLeftToBottomRight) const
  260.     {
  261.         draw(Rect(position.d_x, position.d_y, position.d_x + size.d_width, position.d_y + size.d_height), position.d_z, clip_rect, colours, quad_split_mode);
  262.     }
  263.  
  264.  
  265.     /*!
  266.     \brief
  267.         Queue the image to be drawn.
  268.  
  269.     \note
  270.         The final position of the Image will be adjusted by the offset values defined for this Image object.  If absolute positioning is
  271.         essential then these values should be taken into account prior to calling the draw() methods.  However, by doing this you take
  272.         away the ability of the Imageset designer to adjust the alignment and positioning of Images, therefore your component is far
  273.         less useful since it requires code changes to modify image positioning that could have been handled from a data file.
  274.  
  275.     \param position
  276.         Vector3 object containing the location where the Image is to be drawn
  277.  
  278.     \note
  279.         The image will be drawn at it's internally defined size.
  280.  
  281.     \param clip_rect
  282.         Rect object that defines an on-screen area that the Image will be clipped to when drawing.
  283.  
  284.     \param colours
  285.         ColourRect object that describes the colour values to use for each corner of the Image.
  286.     
  287.     \param quad_split_mode
  288.         One of the QuadSplitMode values specifying the way quads are split into triangles
  289.  
  290.     \return
  291.         Nothing
  292.     */
  293.     void    draw(const Vector3& position, const Rect& clip_rect, const ColourRect& colours, QuadSplitMode quad_split_mode = TopLeftToBottomRight) const
  294.     {
  295.         draw(Rect(position.d_x, position.d_y, position.d_x + getWidth(), position.d_y + getHeight()), position.d_z, clip_rect, colours, quad_split_mode);
  296.     }
  297.  
  298.  
  299.     /*!
  300.     \brief
  301.         Queue the image to be drawn.
  302.  
  303.     \note
  304.         The final position of the Image will be adjusted by the offset values defined for this Image object.  If absolute positioning is
  305.         essential then these values should be taken into account prior to calling the draw() methods.  However, by doing this you take
  306.         away the ability of the Imageset designer to adjust the alignment and positioning of Images, therefore your component is far
  307.         less useful since it requires code changes to modify image positioning that could have been handled from a data file.
  308.  
  309.     \param position
  310.         Vector3 object containing the location where the Image is to be drawn
  311.  
  312.     \param clip_rect
  313.         Rect object that defines an on-screen area that the Image will be clipped to when drawing.
  314.  
  315.     \param top_left_colour
  316.         Colour (as 0xAARRGGBB value) to be applied to the top-left corner of the Image.
  317.  
  318.     \param top_right_colour
  319.         Colour (as 0xAARRGGBB value) to be applied to the top-right corner of the Image.
  320.  
  321.     \param bottom_left_colour
  322.         Colour (as 0xAARRGGBB value) to be applied to the bottom-left corner of the Image.
  323.  
  324.     \param bottom_right_colour
  325.         Colour (as 0xAARRGGBB value) to be applied to the bottom-right corner of the Image.
  326.     
  327.     \param quad_split_mode
  328.         One of the QuadSplitMode values specifying the way quads are split into triangles
  329.  
  330.     \return
  331.         Nothing
  332.     */
  333.     void    draw(const Vector3& position, const Rect& clip_rect, const colour& top_left_colour = 0xFFFFFFFF, const colour& top_right_colour = 0xFFFFFFFF, const colour& bottom_left_colour = 0xFFFFFFFF, const colour& bottom_right_colour = 0xFFFFFFFF, QuadSplitMode quad_split_mode = TopLeftToBottomRight) const
  334.     {
  335.         draw(Rect(position.d_x, position.d_y, position.d_x + getWidth(), position.d_y + getHeight()), position.d_z, clip_rect, ColourRect(top_left_colour, top_right_colour, bottom_left_colour, bottom_right_colour), quad_split_mode);
  336.     }
  337.  
  338.  
  339.     /*!
  340.     \brief
  341.         Queue the image to be drawn.
  342.  
  343.     \note
  344.         The final position of the Image will be adjusted by the offset values defined for this Image object.  If absolute positioning is
  345.         essential then these values should be taken into account prior to calling the draw() methods.  However, by doing this you take
  346.         away the ability of the Imageset designer to adjust the alignment and positioning of Images, therefore your component is far
  347.         less useful since it requires code changes to modify image positioning that could have been handled from a data file.
  348.  
  349.     \param dest_rect
  350.         Rect object defining the area on-screen where the Image is to be drawn.  The Image will be scaled to fit the area as required.
  351.  
  352.     \param z
  353.         Z-order position for the image.  Positions increase "into the screen", so 0.0f is at the top of the z-order.
  354.  
  355.     \param clip_rect
  356.         Rect object that defines an on-screen area that the Image will be clipped to when drawing.
  357.  
  358.     \param colours
  359.         ColourRect object that describes the colour values to use for each corner of the Image.
  360.     
  361.     \param quad_split_mode
  362.         One of the QuadSplitMode values specifying the way quads are split into triangles
  363.  
  364.     \return
  365.         Nothing
  366.     */
  367.     void    draw(const Rect& dest_rect, float z, const Rect& clip_rect,const ColourRect& colours, QuadSplitMode quad_split_mode = TopLeftToBottomRight) const;
  368.  
  369.  
  370.     /*!
  371.     \brief
  372.         Writes an xml representation of this Image object to \a out_stream.
  373.  
  374.     \param out_stream
  375.         Stream where xml data should be output.
  376.  
  377.     \return
  378.         Nothing.
  379.     */
  380.     void writeXMLToStream(OutStream& out_stream) const;
  381.  
  382.  
  383.     friend class std::map<String, Image>;
  384.     friend struct std::pair<const String, Image>;
  385.  
  386.  
  387.     /*************************************************************************
  388.         Construction and Destruction
  389.     *************************************************************************/
  390.     /*!
  391.     \brief
  392.         Default constructor (only used by std::map)
  393.     */
  394.     Image(void) {}
  395.  
  396.  
  397.     /*!
  398.     \brief
  399.         Constructor for Image objects.  This is not normally used directly by client code, use the Imageset interface instead.
  400.  
  401.     \param owner
  402.         Pointer to a Imageset object that owns this Image.  This must not be NULL.
  403.         
  404.     \param name
  405.         String object describing the name of the image being created.
  406.         
  407.     \param area
  408.         Rect object describing an area that will be associated with this image.
  409.         
  410.     \param render_offset
  411.         Point object that describes the offset to be applied when rendering this image.
  412.         
  413.     \param horzScaling
  414.         float value indicating the initial horizontal scaling to be applied to this image.
  415.  
  416.     \param vertScaling
  417.         float value indicating the initial vertical scaling to be applied to this image.
  418.  
  419.     \exception NullObjectException    Thrown if \a owner was NULL.
  420.     */
  421.     Image(const Imageset* owner, const String& name, const Rect& area, const Point& render_offset, float horzScaling = 1.0f, float vertScaling = 1.0f);
  422.  
  423.  
  424.  
  425.     /*!
  426.     \brief
  427.         Copy constructor
  428.     */
  429.     Image(const Image& image);
  430.  
  431.  
  432.     /*!
  433.     \brief
  434.         Destructor for Image objects.
  435.     */
  436.     ~Image(void);
  437.  
  438.  
  439. private:
  440.     /*************************************************************************
  441.         Friends
  442.     *************************************************************************/
  443.     friend class Imageset;
  444.  
  445.         
  446.     /*************************************************************************
  447.         Implementation Methods
  448.     *************************************************************************/
  449.     /*!
  450.     \brief
  451.         set the horizontal scaling factor to be applied to this Image
  452.  
  453.     \param factor
  454.         float value describing the scaling factor required.
  455.  
  456.     \return
  457.         Nothing.
  458.     */
  459.     void    setHorzScaling(float factor);
  460.  
  461.  
  462.     /*!
  463.     \brief
  464.         set the vertical scaling factor to be applied to this Image
  465.  
  466.     \param factor
  467.         float value describing the scaling factor required.
  468.  
  469.     \return
  470.         Nothing.
  471.     */
  472.     void    setVertScaling(float factor);
  473.  
  474.  
  475.     /*************************************************************************
  476.         Implementation Data
  477.     *************************************************************************/
  478.     const Imageset*    d_owner;        //!< Link back to Imageset that owns this image
  479.     Rect            d_area;            //!< Rect defining the area on the texture that makes up this image.
  480.     Point            d_offset;        //!< Offset to use when rendering
  481.  
  482.     // image auto-scaling fields.
  483.     float    d_scaledWidth;        //!< scaled image width.
  484.     float    d_scaledHeight;        //!< scaled image height.
  485.     Point    d_scaledOffset;        //!< scaled rendering offset.
  486.     String    d_name;                //!< name of this image.
  487. };
  488.  
  489. } // End of  CEGUI namespace section
  490.  
  491. #if defined(_MSC_VER)
  492. #    pragma warning(pop)
  493. #endif
  494.  
  495. #endif    // end of guard _CEGUIImage_h_
  496.